// interface/storage_interface.h
#ifndef STORAGE_INTERFACE_H
#define STORAGE_INTERFACE_H

#include <stdint.h>
#include <stdbool.h>
#include "esp_err.h"

// 前向声明
typedef struct storage_context_t storage_context_t;

/**
 * @brief 存储抽象接口
 */
typedef struct {
    // 核心操作接口
    esp_err_t (*init)(storage_context_t* ctx, const void* config);
    esp_err_t (*deinit)(storage_context_t* ctx);
    
    // 文件操作接口
    esp_err_t (*read)(storage_context_t* ctx, const char* path, void* data, 
                      size_t size, size_t* read_size);
    esp_err_t (*write)(storage_context_t* ctx, const char* path,
                       const void* data, size_t size);
    esp_err_t (*append)(storage_context_t* ctx, const char* path, 
                        const void* data, size_t size);
    esp_err_t (*remove)(storage_context_t* ctx, const char* path);
    esp_err_t (*rename)(storage_context_t* ctx, const char* old_path,
                        const char* new_path);
    
    // 目录操作接口
    esp_err_t (*mkdir)(storage_context_t* ctx, const char* path);
    esp_err_t (*rmdir)(storage_context_t* ctx, const char* path);
    esp_err_t (*stat)(storage_context_t* ctx, const char* path, void* st);
    esp_err_t (*exists)(storage_context_t* ctx, const char* path, bool* exists);
    esp_err_t (*list)(storage_context_t* ctx, const char* path, void* files,
                      size_t* count);
    
    // 系统接口
    esp_err_t (*format)(storage_context_t* ctx);
    esp_err_t (*get_info)(storage_context_t* ctx, uint32_t* total, uint32_t* used);

} storage_interface_t;

#endif /* STORAGE_INTERFACE_H */

// interface/storage_extension_interface.h
#ifndef STORAGE_EXTENSION_INTERFACE_H 
#define STORAGE_EXTENSION_INTERFACE_H

#include <stdint.h>
#include "esp_err.h"

// 前向声明
typedef struct storage_context_t storage_context_t;

/**
 * @brief 存储扩展功能接口
 */
typedef struct {
    // 异步操作接口
    esp_err_t (*async_read)(storage_context_t* ctx, const char* path,
                           void* data, size_t size, void* callback, void* arg);
    esp_err_t (*async_write)(storage_context_t* ctx, const char* path,
                            const void* data, size_t size, void* callback, void* arg);
    esp_err_t (*async_cancel)(storage_context_t* ctx, const char* path);
    
    // DMA操作接口
    esp_err_t (*dma_read)(storage_context_t* ctx, const char* path,
                         void* callback, void* arg);
    esp_err_t (*dma_write)(storage_context_t* ctx, const char* path,
                          void* callback, void* arg);
    
    // 缓存管理接口
    esp_err_t (*cache_enable)(storage_context_t* ctx, bool enable);
    esp_err_t (*cache_prefetch)(storage_context_t* ctx, const char* path);
    esp_err_t (*cache_flush)(storage_context_t* ctx);
    
    // 数据保护接口
    esp_err_t (*protect_write)(storage_context_t* ctx, const char* path,
                              const void* data, size_t size);
    esp_err_t (*protect_read)(storage_context_t* ctx, const char* path,
                             void* data, size_t size, size_t* read_size);
    esp_err_t (*check_consistency)(storage_context_t* ctx);
    esp_err_t (*recover_consistency)(storage_context_t* ctx);
    
    // 错误处理接口
    esp_err_t (*get_last_error)(storage_context_t* ctx, void* error);
    esp_err_t (*error_recover)(storage_context_t* ctx, int type);
    
} storage_extension_interface_t;

#endif /* STORAGE_EXTENSION_INTERFACE_H */

// interface/storage_device_interface.h 
#ifndef STORAGE_DEVICE_INTERFACE_H
#define STORAGE_DEVICE_INTERFACE_H

#include <stdint.h>
#include "esp_err.h"

/**
 * @brief 存储设备抽象接口
 */
typedef struct {
    // 设备操作接口
    esp_err_t (*init)(void* config);
    esp_err_t (*deinit)(void);
    esp_err_t (*read)(void* buf, size_t size, size_t* read_size); 
    esp_err_t (*write)(const void* buf, size_t size);
    esp_err_t (*flush)(void);
    esp_err_t (*ioctl)(int cmd, void* arg);
    
} storage_device_interface_t;

#endif /* STORAGE_DEVICE_INTERFACE_H */


// core/include/storage.h
#ifndef STORAGE_H
#define STORAGE_H

#include <stdint.h>
#include "esp_err.h"
#include "storage_interface.h"
#include "storage_device_interface.h"
#include "storage_extension_interface.h"
#include "storage_types.h"

/**
 * @brief 初始化存储上下文
 */
esp_err_t storage_init(storage_context_t* ctx, const storage_config_t* config);

/**
 * @brief 注销存储上下文
 */
void storage_deinit(storage_context_t* ctx);

/**
 * @brief 获取存储接口实例
 */
const storage_interface_t* storage_get_interface(void);

/**
 * @brief 获取存储扩展接口实例
 */
const storage_extension_interface_t* storage_get_extension(void);

/**
 * @brief 注册存储设备
 */
esp_err_t storage_register_device(storage_context_t* ctx, 
                                const storage_device_interface_t* device,
                                const void* config);

/**
 * @brief 解注册存储设备
 */
esp_err_t storage_unregister_device(storage_context_t* ctx);

#endif /* STORAGE_H */

#ifndef STORAGE_TYPES_H
#define STORAGE_TYPES_H

#include <stdint.h>
#include <time.h>
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include "freertos/task.h"
#include "esp_err.h"

// 基本定义
#define FILE_PATH_MAX 256
#define FILE_NAME_MAX 64

// 缓存配置
#define MAX_CACHE_ENTRIES 16
#define MAX_CACHE_SIZE (64 * 1024)  // 64KB总缓存
#define FS_READ_BUFFER_SIZE (4 * 1024)

// DMA配置
#define DMA_BUFFER_SIZE (32 * 1024)  // 32KB per buffer 
#define NUM_DMA_BUFFERS 2
#define DMA_OPTIMAL_BLOCK_SIZE (16 * 1024)  // 16KB最佳传输块大小
#define DMA_MAX_SCATTER_GATHER 8            // 最大分散/聚集数量
#define DMA_PREFETCH_SIZE (32 * 1024)       // 32KB预取大小

// 异步操作配置
#define MAX_ASYNC_OPERATIONS 8
#define ASYNC_TASK_STACK_SIZE 4096
#define ASYNC_TASK_PRIORITY 5


// 前向声明 
struct fs_cache_entry_t;
struct fs_cache_t;
struct dma_manager_t;
struct transaction_data_t;

// 存储设备类型
typedef enum {
    STORAGE_TYPE_FLASH,
    STORAGE_TYPE_SD,
    STORAGE_TYPE_MAX
} storage_device_type_t;

// 文件信息结构
typedef struct {
    char name[FILE_NAME_MAX];
    size_t size;
    bool is_directory;
    time_t modified_time;
} file_info_t;

// 存储设备操作接口
typedef struct {
    esp_err_t (*init)(void *config);
    esp_err_t (*deinit)(void);
    esp_err_t (*read)(void *buf, size_t size, size_t *read_size);
    esp_err_t (*write)(const void *buf, size_t size);
    esp_err_t (*flush)(void);
} storage_ops_t;

// 存储设备配置
typedef struct {
    union {
        struct {
            const char *partition_label;
        } flash_config;
        
        struct {
            int miso_pin;
            int mosi_pin;
            int sck_pin;
            int cs_pin;
        } sd_config;
    };
} storage_config_t;

// 存储设备实例
typedef struct {
    storage_device_type_t type;
    storage_ops_t ops;
    storage_config_t config;
} storage_device_t;

// 缓存条目结构
typedef struct fs_cache_entry_t {
    char *path;                  // 文件路径
    uint8_t *data;              // 缓存数据
    size_t size;                // 数据大小
    size_t capacity;            // 缓冲区容量
    bool dirty;                 // 是否需要回写
    time_t last_access;         // 最后访问时间
    uint32_t access_count;      // 访问计数
    bool is_prefetch;           // 是否为预读取数据
} fs_cache_entry_t;

// 缓存管理器结构
typedef struct fs_cache_t {
    fs_cache_entry_t *entries;   // 缓存条目数组
    size_t count;                // 当前缓存条目数
    size_t capacity;             // 最大缓存条目数 
    size_t max_cache_size;       // 最大缓存大小
    struct {
        uint32_t cache_hits;
        uint32_t cache_misses;
        uint32_t buffer_flushes;
        uint64_t total_read_time;
        uint64_t total_write_time;
    } stats;                     // 性能统计信息
    bool prefetch_enabled;       // 是否启用预读取
} fs_cache_t;

// 文件系统配置
typedef struct {
    char base_path[64];        
    char partition_label[16];  
    bool format_if_mount_failed;
    storage_device_t *storage_dev;
    struct {
        int miso_pin;
        int mosi_pin;
        int sck_pin;
        int cs_pin;
    } sd_config;
} fs_config_t;

// 文件系统实例
typedef struct {
    fs_config_t config;          // 文件系统配置
    bool mounted;                // 挂载状态
    SemaphoreHandle_t mutex;     // 互斥锁
    fs_cache_t *cache;           // 缓存管理器
    struct dma_manager_t *dma_mgr;  // DMA管理器
    struct transaction_data_t *transaction; // 事务管理器
} file_system_t;



#endif /* STORAGE_TYPES_H */

// core/include/storage_protection.h
#ifndef STORAGE_PROTECTION_H
#define STORAGE_PROTECTION_H

#include <stdint.h>
#include <time.h>
#include "esp_err.h"
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include "esp_crc.h"
#include "esp_system.h"
#include "storage_types.h"

// 保护相关常量定义
#define CRC32_INITIAL_VALUE 0xFFFFFFFF
#define PROTECTION_MAGIC_NUMBER 0xAA55AA55
#define JOURNAL_BLOCK_SIZE 4096

// 数据保护状态枚举
typedef enum {
    PROTECTION_STATUS_OK = 0,
    PROTECTION_STATUS_CRC_ERROR,
    PROTECTION_STATUS_POWER_FAIL,
    PROTECTION_STATUS_INCONSISTENT,
    PROTECTION_STATUS_JOURNAL_ERROR,
    PROTECTION_STATUS_MAX
} protection_status_t;

// 数据保护元数据结构
typedef struct {
    uint32_t magic;              // 魔数标识
    uint32_t sequence;           // 序列号
    uint32_t data_size;          // 数据大小
    uint32_t crc32;             // CRC32校验值
    time_t timestamp;           // 时间戳
    struct {
        uint32_t flags;         // 保护标志位
        uint32_t reserved[4];   // 保留字段
    } extra;                    // 扩展信息
} protection_metadata_t;

// 文件系统保护上下文
typedef struct {
    protection_metadata_t *metadata;         // 保护元数据
    char journal_path[FILE_PATH_MAX];        // journal文件路径
    SemaphoreHandle_t mutex;                 // 保护互斥锁
    struct {
        bool enabled;                        // 保护功能开关
        bool auto_recover;                   // 自动恢复开关
        uint32_t journal_size;               // journal大小限制
        uint32_t sync_interval;              // 同步间隔(ms)
    } config;                                // 保护配置
} fs_protection_t;

// 数据保护函数声明
esp_err_t fs_protection_init(file_system_t *fs);
void fs_protection_deinit(file_system_t *fs);

// CRC校验相关函数
esp_err_t fs_calc_crc32(const void *data, size_t size, uint32_t *crc);
esp_err_t fs_verify_crc32(const void *data, size_t size, uint32_t expected_crc);

// 保护读写函数
esp_err_t fs_write_protected(file_system_t *fs, const char *path, 
                           const void *data, size_t size);
                           
esp_err_t fs_read_protected(file_system_t *fs, const char *path,
                          void *data, size_t size, size_t *read_size);

// 一致性检查和恢复函数
esp_err_t fs_check_consistency(file_system_t *fs);
esp_err_t fs_recover_consistency(file_system_t *fs);

// Journal管理函数
esp_err_t fs_journal_init(file_system_t *fs);
esp_err_t fs_journal_sync(file_system_t *fs);
void fs_journal_cleanup(file_system_t *fs);

// 保护配置函数
esp_err_t fs_protection_configure(file_system_t *fs, const void *config);
esp_err_t fs_protection_get_status(file_system_t *fs, protection_status_t *status);

#endif /* STORAGE_PROTECTION_H */


// core/include/storage_power_protection.h
#ifndef STORAGE_POWER_PROTECTION_H
#define STORAGE_POWER_PROTECTION_H

#include <stdint.h>
#include "esp_err.h"
#include "storage_types.h"

// 断电保护相关常量
#define TRANSACTION_MAGIC 0xABCD1234
#define TRANSACTION_PATH "/.transaction"
#define BACKUP_PATH "/.backup"
#define TRANSACTION_TIMEOUT_MS 5000

// 事务状态枚举
typedef enum {
    TRANSACTION_NONE = 0,
    TRANSACTION_STARTED,
    TRANSACTION_COMMITTED,
    TRANSACTION_ROLLBACK,
    TRANSACTION_ERROR
} transaction_status_t;

// 事务头部结构
typedef struct {
    uint32_t magic;                // 魔数标识
    uint32_t sequence;             // 序列号
    uint32_t checksum;            // 校验和
    transaction_status_t status;   // 事务状态
    size_t data_size;             // 数据大小
    char path[FILE_PATH_MAX];      // 目标文件路径
    struct {
        time_t timestamp;          // 时间戳
        uint32_t flags;            // 标志位
        uint32_t reserved[2];      // 保留字段
    } extra;                       // 扩展信息
} transaction_header_t;

// 事务数据结构
typedef struct {
    transaction_header_t header;    // 事务头部
    uint8_t *data;                 // 数据缓冲区
    size_t size;                   // 缓冲区大小
    bool in_progress;              // 事务进行标志
    struct {
        bool auto_rollback;        // 自动回滚开关
        uint32_t timeout;          // 超时时间(ms)
        uint32_t retry_count;      // 重试次数
    } config;                      // 事务配置
} transaction_data_t;

// 事务管理函数声明
esp_err_t fs_transaction_begin(file_system_t *fs);
esp_err_t fs_transaction_commit(file_system_t *fs);
esp_err_t fs_transaction_rollback(file_system_t *fs);
esp_err_t fs_power_fail_recover(file_system_t *fs);

// 事务配置函数
esp_err_t fs_transaction_configure(file_system_t *fs, const void *config);
esp_err_t fs_transaction_get_status(file_system_t *fs, transaction_status_t *status);

#endif /* STORAGE_POWER_PROTECTION_H */


// core/include/storage_perf.h
#ifndef STORAGE_PERF_H
#define STORAGE_PERF_H

#include <stdint.h>
#include "esp_err.h"
#include "storage_types.h"

// 性能计数器结构 
typedef struct {
    uint32_t cache_hits;         // 缓存命中次数
    uint32_t cache_misses;       // 缓存未命中次数
    uint32_t dma_transfers;      // DMA传输次数
    uint32_t buffer_flushes;     // 缓冲区刷新次数
    uint64_t total_read_time;    // 总读取时间(μs)
    uint64_t total_write_time;   // 总写入时间(μs)
    struct {
        uint32_t read_ops;       // 读操作次数
        uint32_t write_ops;      // 写操作次数
        uint32_t async_ops;      // 异步操作次数
        uint32_t error_count;    // 错误次数
    } operations;                // 操作统计
} fs_perf_stats_t;

// 性能监控配置
typedef struct {
    bool enable_monitoring;      // 启用性能监控
    bool collect_detailed_stats; // 收集详细统计
    uint32_t sample_interval;    // 采样间隔(ms)
    size_t history_size;         // 历史记录大小
} fs_perf_config_t;

// 性能优化配置
typedef struct {
    bool enable_prefetch;        // 启用预读取
    bool optimize_small_io;      // 优化小IO
    bool enable_write_cache;     // 启用写缓存
    uint32_t cache_flush_interval; // 缓存刷新间隔(ms)
} fs_perf_opt_config_t;

// 性能相关函数声明
esp_err_t fs_enable_prefetch(file_system_t *fs, bool enable);
esp_err_t fs_prefetch_file(file_system_t *fs, const char *path);

// 性能统计接口
esp_err_t fs_get_stats(file_system_t *fs, fs_perf_stats_t *stats);
void fs_reset_stats(file_system_t *fs);
esp_err_t fs_get_detailed_stats(file_system_t *fs, void *detailed_stats, size_t *size);

// 性能优化接口
esp_err_t fs_optimize_performance(file_system_t *fs, const fs_perf_opt_config_t *config);
esp_err_t fs_set_monitoring_config(file_system_t *fs, const fs_perf_config_t *config);

// 性能阈值配置
esp_err_t fs_set_performance_threshold(file_system_t *fs, 
                                     const char *metric,
                                     uint32_t threshold);

// 性能回调注册
typedef void (*fs_perf_callback_t)(void *ctx, const char *metric, uint32_t value);
esp_err_t fs_register_perf_callback(file_system_t *fs, 
                                   const char *metric,
                                   fs_perf_callback_t callback,
                                   void *ctx);

#endif /* STORAGE_PERF_H */

// core/include/storage_error.h
#ifndef STORAGE_ERROR_H
#define STORAGE_ERROR_H

#include <time.h>
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include "esp_err.h"

// 错误类型枚举
typedef enum {
    FS_ERROR_NONE = 0,
    FS_ERROR_DEVICE_FAIL,    // 设备级错误
    FS_ERROR_FS_CORRUPT,     // 文件系统损坏
    FS_ERROR_DMA_FAIL,       // DMA传输错误
    FS_ERROR_CACHE_FAIL,     // 缓存操作错误
    FS_ERROR_PROTECTION,     // 保护机制错误
    FS_ERROR_ASYNC,          // 异步操作错误
    FS_ERROR_TIMEOUT,        // 操作超时
    FS_ERROR_MAX
} fs_error_type_t;

// 错误信息结构
typedef struct {
    fs_error_type_t type;    // 错误类型
    uint32_t code;           // 错误码
    uint32_t retry_count;    // 重试次数
    char location[64];       // 错误发生位置
    time_t timestamp;        // 错误发生时间
    struct {
        uint32_t value;      // 附加错误值
        char info[128];      // 附加错误信息
    } extra;                 // 扩展错误信息
} fs_error_info_t;

// 错误处理上下文
typedef struct {
    fs_error_info_t errors[16];    // 错误历史记录(循环缓冲)
    size_t error_count;            // 错误计数
    size_t error_index;            // 当前错误索引
    SemaphoreHandle_t mutex;       // 错误处理互斥锁
    struct {
        bool auto_recover;         // 是否自动恢复
        uint32_t retry_limit;      // 最大重试次数
        uint32_t recover_timeout;  // 恢复超时时间
    } config;                      // 错误处理配置
} fs_error_ctx_t;

// 错误处理接口函数声明
esp_err_t fs_error_init(void* ctx);
void fs_error_deinit(void* ctx);
void fs_error_record(void* ctx, fs_error_type_t type, uint32_t code, const char* location);
esp_err_t fs_error_recover(void* ctx, fs_error_type_t type);
esp_err_t fs_get_last_error(void* ctx, fs_error_info_t* error);
void fs_clear_errors(void* ctx);

#endif /* STORAGE_ERROR_H */

// core/include/storage_dma.h
#ifndef STORAGE_DMA_H
#define STORAGE_DMA_H

#include <stdint.h>
#include "esp_err.h"
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include "storage_types.h"

// DMA传输模式
typedef enum {
    DMA_MODE_SINGLE,       // 单次传输
    DMA_MODE_SCATTER,      // 分散写入
    DMA_MODE_GATHER,       // 聚集读取
    DMA_MODE_CIRCULAR      // 循环传输
} dma_transfer_mode_t;

// DMA传输描述符
typedef struct {
    void *buf;            // 缓冲区指针
    size_t size;          // 缓冲区大小
    size_t offset;        // 传输偏移
    uint32_t flags;       // 传输标志
} dma_descriptor_t;

// DMA缓冲区结构
typedef struct {
    uint8_t *buffer;          // DMA缓冲区
    size_t size;             // 缓冲区大小
    bool in_use;             // 使用标志
    SemaphoreHandle_t mutex; // 互斥锁
} dma_buffer_t;

// DMA管理器结构
typedef struct dma_manager_t {
    dma_buffer_t buffers[NUM_DMA_BUFFERS];    // DMA缓冲区数组
    SemaphoreHandle_t buffer_switch_mutex;     // 缓冲区切换互斥锁
    uint8_t current_write_buffer;             // 当前写入缓冲区
    uint8_t current_read_buffer;              // 当前读取缓冲区
    void *optimization_ctx;                   // 优化上下文
    struct {
        bool optimize_transfer;               // 优化传输开关
        uint32_t timeout;                     // 传输超时时间
        size_t max_transfer_size;             // 最大传输大小
        uint8_t priority;                     // DMA传输优先级
    } config;                                 // DMA配置
} dma_manager_t;

// DMA回调函数类型
typedef size_t (*dma_data_callback_t)(void *buffer, size_t size, void *user_data);
typedef bool (*dma_process_callback_t)(const void *buffer, size_t size, void *user_data);

// DMA 初始化/清理函数
esp_err_t file_system_init_dma(file_system_t *fs);
esp_err_t file_system_deinit_dma(file_system_t *fs);

// DMA传输函数
esp_err_t file_system_write_dma(file_system_t *fs, const char *path,
                               dma_data_callback_t data_cb, void *user_data);
                               
esp_err_t file_system_read_dma(file_system_t *fs, const char *path,
                              dma_process_callback_t process_cb, void *user_data);

// DMA优化函数
esp_err_t dma_optimize_transfer(file_system_t *fs, dma_transfer_mode_t mode);
esp_err_t dma_set_descriptor_chain(file_system_t *fs, dma_descriptor_t *desc, size_t count);
esp_err_t dma_start_transfer(file_system_t *fs);
esp_err_t dma_wait_complete(file_system_t *fs, TickType_t timeout);

// DMA配置函数
esp_err_t dma_set_config(file_system_t *fs, const void *config);
esp_err_t dma_get_config(file_system_t *fs, void *config);

// DMA状态查询函数
esp_err_t dma_get_transfer_status(file_system_t *fs, size_t *transferred_size);
esp_err_t dma_is_transfer_complete(file_system_t *fs, bool *complete);

#endif /* STORAGE_DMA_H */


// core/include/storage_device.h
#ifndef STORAGE_DEVICE_H
#define STORAGE_DEVICE_H

#include <stdint.h>
#include "esp_err.h"
#include "storage_types.h"

// 设备类型枚举
typedef enum {
    STORAGE_DEVICE_FLASH,    // 内部Flash
    STORAGE_DEVICE_SD,       // SD卡
    STORAGE_DEVICE_EMMC,     // eMMC
    STORAGE_DEVICE_USB,      // USB存储
    STORAGE_DEVICE_CUSTOM    // 自定义设备
} storage_device_type_t;

// 设备能力标志
typedef enum {
    STORAGE_CAP_READ         = (1 << 0),  // 读取能力
    STORAGE_CAP_WRITE        = (1 << 1),  // 写入能力
    STORAGE_CAP_ERASE        = (1 << 2),  // 擦除能力
    STORAGE_CAP_DMA          = (1 << 3),  // DMA支持
    STORAGE_CAP_TRIM        = (1 << 4),   // TRIM支持
    STORAGE_CAP_SECURE      = (1 << 5)    // 安全存储支持
} storage_device_caps_t;

// 设备状态枚举
typedef enum {
    STORAGE_DEVICE_UNINITIALIZED,    // 未初始化
    STORAGE_DEVICE_INITIALIZED,       // 已初始化
    STORAGE_DEVICE_ACTIVE,           // 活动状态
    STORAGE_DEVICE_SUSPENDED,        // 挂起状态
    STORAGE_DEVICE_ERROR             // 错误状态
} storage_device_state_t;

// 设备配置结构
typedef struct {
    storage_device_type_t type;      // 设备类型
    uint32_t capabilities;           // 设备能力
    union {
        struct {
            const char *partition_label;  // 分区标签
            size_t partition_size;        // 分区大小
        } flash_config;                   // Flash配置
        
        struct {
            int miso_pin;                 // MISO引脚
            int mosi_pin;                 // MOSI引脚
            int sck_pin;                  // SCK引脚
            int cs_pin;                   // CS引脚
            int max_freq_khz;             // 最大频率
        } sd_config;                      // SD卡配置
        
        void *custom_config;              // 自定义配置
    };
    
    struct {
        uint32_t timeout_ms;              // 操作超时
        bool enable_retry;                // 启用重试
        uint8_t retry_count;              // 重试次数
        bool enable_cache;                // 启用缓存
    } options;                            // 通用选项
} storage_device_config_t;

// 设备操作接口
typedef struct {
    // 基本操作
    esp_err_t (*init)(void *config);
    esp_err_t (*deinit)(void);
    esp_err_t (*read)(void *buf, size_t size, size_t *read_size);
    esp_err_t (*write)(const void *buf, size_t size);
    esp_err_t (*flush)(void);
    
    // 扩展操作
    esp_err_t (*erase)(size_t offset, size_t size);
    esp_err_t (*trim)(size_t offset, size_t size);
    esp_err_t (*ioctl)(int cmd, void *arg);
    esp_err_t (*suspend)(void);
    esp_err_t (*resume)(void);
    
    // 状态查询
    esp_err_t (*get_state)(storage_device_state_t *state);
    esp_err_t (*get_info)(void *info);
} storage_device_ops_t;

// 设备实例结构
typedef struct {
    storage_device_type_t type;          // 设备类型
    storage_device_ops_t ops;            // 设备操作接口
    storage_device_config_t config;      // 设备配置
    storage_device_state_t state;        // 设备状态
    void *driver_ctx;                    // 驱动上下文
} storage_device_t;

// 设备管理函数声明
esp_err_t storage_device_register(storage_device_t *dev, const storage_device_config_t *config);
esp_err_t storage_device_unregister(storage_device_t *dev);
esp_err_t storage_device_suspend(storage_device_t *dev);
esp_err_t storage_device_resume(storage_device_t *dev);
esp_err_t storage_device_get_info(storage_device_t *dev, void *info);
esp_err_t storage_device_check_capability(storage_device_t *dev, storage_device_caps_t cap);

#endif /* STORAGE_DEVICE_H */

// core/include/storage_config.h
#ifndef STORAGE_CONFIG_H
#define STORAGE_CONFIG_H

#include <stdint.h>

// Cache Configuration 
typedef struct {
    size_t max_entries;        // 最大缓存条目数
    size_t max_size;           // 最大缓存大小(字节)
    size_t buffer_size;        // 读取缓冲区大小
    bool enable_prefetch;      // 是否启用预读取
} cache_config_t;

// DMA Configuration
typedef struct {
    size_t buffer_size;        // DMA缓冲区大小
    uint8_t buffer_count;      // DMA缓冲区数量
    size_t optimal_size;       // 最佳传输块大小
    uint8_t max_sg;           // 最大分散/聚集数量
    size_t prefetch_size;     // 预读取大小
    bool optimize_transfer;    // 是否优化传输
} dma_config_t;

// Async Configuration
typedef struct {
    size_t max_operations;     // 最大并发操作数
    size_t stack_size;         // 任务栈大小
    uint8_t priority;          // 任务优先级
    bool enable_callback;      // 是否启用回调
} async_config_t;

// Storage System Configuration
typedef struct {
    cache_config_t cache;      // 缓存配置
    dma_config_t dma;         // DMA配置  
    async_config_t async;      // 异步配置
    
    struct {
        bool format_if_mount_failed;  // 挂载失败时是否格式化
        bool enable_protection;        // 是否启用数据保护
        bool enable_transactions;      // 是否启用事务支持
        bool enable_async;            // 是否启用异步操作
    } flags;                          // 功能开关
    
} storage_system_config_t;

// 默认配置值
#define STORAGE_CACHE_DEFAULT_CONFIG() { \
    .max_entries = 16, \
    .max_size = 64 * 1024, \
    .buffer_size = 4 * 1024, \
    .enable_prefetch = true \
}

#define STORAGE_DMA_DEFAULT_CONFIG() { \
    .buffer_size = 32 * 1024, \
    .buffer_count = 2, \
    .optimal_size = 16 * 1024, \
    .max_sg = 8, \
    .prefetch_size = 32 * 1024, \
    .optimize_transfer = true \
}

#define STORAGE_ASYNC_DEFAULT_CONFIG() { \
    .max_operations = 8, \
    .stack_size = 4096, \
    .priority = 5, \
    .enable_callback = true \
}

#define STORAGE_SYSTEM_DEFAULT_CONFIG() { \
    .cache = STORAGE_CACHE_DEFAULT_CONFIG(), \
    .dma = STORAGE_DMA_DEFAULT_CONFIG(), \
    .async = STORAGE_ASYNC_DEFAULT_CONFIG(), \
    .flags = { \
        .format_if_mount_failed = true, \
        .enable_protection = true, \
        .enable_transactions = true, \
        .enable_async = true \
    } \
}

#endif /* STORAGE_CONFIG_H */


// core/include/storage_cache.h
#ifndef STORAGE_CACHE_H
#define STORAGE_CACHE_H

#include <stdint.h>
#include <time.h>
#include "esp_err.h"
#include "storage_types.h"

// 缓存策略枚举
typedef enum {
    CACHE_POLICY_LRU,     // 最近最少使用
    CACHE_POLICY_LFU,     // 最不经常使用
    CACHE_POLICY_FIFO,    // 先进先出
    CACHE_POLICY_CUSTOM   // 自定义策略
} cache_policy_t;

// 缓存入口点结构
typedef struct fs_cache_entry_t {
    char *path;                  // 文件路径
    uint8_t *data;              // 缓存数据
    size_t size;                // 数据大小
    size_t capacity;            // 缓冲区容量
    bool dirty;                 // 是否需要回写
    time_t last_access;         // 最后访问时间
    uint32_t access_count;      // 访问计数
    bool is_prefetch;           // 是否为预读取数据
    struct {
        uint32_t priority;      // 缓存优先级
        uint32_t lifetime;      // 生命周期(秒)
        bool persistent;        // 是否持久化
    } attributes;               // 缓存属性
} fs_cache_entry_t;

// 缓存管理器函数声明
esp_err_t file_system_init_cache(file_system_t *fs);
void file_system_deinit_cache(file_system_t *fs);

// 缓存操作函数
fs_cache_entry_t* find_cache_entry(file_system_t *fs, const char *path);
esp_err_t add_to_cache(file_system_t *fs, const char *path,
                      const uint8_t *data, size_t size);
void evict_cache_entry(file_system_t *fs);
void file_system_flush_cache(file_system_t *fs);

// 缓存策略管理
esp_err_t cache_set_policy(file_system_t *fs, cache_policy_t policy);
esp_err_t cache_set_custom_policy(file_system_t *fs, void *policy_config);

// 缓存属性管理
esp_err_t cache_set_entry_attributes(file_system_t *fs, const char *path,
                                   const void *attributes);
esp_err_t cache_get_entry_attributes(file_system_t *fs, const char *path,
                                   void *attributes);

// 缓存预读取管理
esp_err_t cache_configure_prefetch(file_system_t *fs, const void *config);
esp_err_t cache_trigger_prefetch(file_system_t *fs, const char *path);

// 缓存统计查询
esp_err_t cache_get_stats(file_system_t *fs, void *stats);
esp_err_t cache_reset_stats(file_system_t *fs);

// 缓存调试接口
esp_err_t cache_dump_info(file_system_t *fs, void *buffer, size_t *size);
esp_err_t cache_verify_integrity(file_system_t *fs);

#endif /* STORAGE_CACHE_H */



// core/include/storage_async.h
#ifndef STORAGE_ASYNC_H
#define STORAGE_ASYNC_H

#include <stdint.h>
#include "esp_err.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "storage_types.h"

// 异步操作状态枚举
typedef enum {
    ASYNC_STATE_IDLE = 0,
    ASYNC_STATE_QUEUED,
    ASYNC_STATE_IN_PROGRESS,
    ASYNC_STATE_COMPLETED,
    ASYNC_STATE_ERROR,
    ASYNC_STATE_CANCELLED
} async_state_t;

// 异步操作类型
typedef enum {
    ASYNC_OP_READ,
    ASYNC_OP_WRITE,
    ASYNC_OP_DELETE,
    ASYNC_OP_RENAME,
    ASYNC_OP_CUSTOM
} async_op_type_t;

// 异步操作回调函数
typedef void (*async_callback_t)(void *context, esp_err_t result);

// 异步操作描述符
typedef struct {
    async_op_type_t type;         // 操作类型
    char *path;                   // 文件路径
    void *buffer;                 // 数据缓冲区
    size_t size;                  // 数据大小
    async_state_t state;          // 操作状态
    async_callback_t callback;     // 完成回调
    void *context;                // 回调上下文
    TaskHandle_t task;            // 任务句柄
    struct {
        uint32_t priority;        // 操作优先级
        TickType_t timeout;       // 超时时间
        bool auto_retry;          // 自动重试
    } config;                     // 操作配置
} async_operation_t;

// 异步操作函数声明
esp_err_t async_read(file_system_t *fs, const char *path,
                    void *data, size_t size,
                    async_callback_t callback, void *context);
                    
esp_err_t async_write(file_system_t *fs, const char *path,
                     const void *data, size_t size,
                     async_callback_t callback, void *context);

esp_err_t async_cancel(file_system_t *fs, const char *path);
esp_err_t async_wait(file_system_t *fs, const char *path, TickType_t timeout);
async_state_t async_get_state(file_system_t *fs, const char *path);

// 异步操作管理接口
esp_err_t async_set_priority(file_system_t *fs, const char *path, uint32_t priority);
esp_err_t async_set_timeout(file_system_t *fs, const char *path, TickType_t timeout);
esp_err_t async_enable_auto_retry(file_system_t *fs, const char *path, bool enable);

// 异步队列管理
esp_err_t async_pause_queue(file_system_t *fs);
esp_err_t async_resume_queue(file_system_t *fs);
esp_err_t async_clear_queue(file_system_t *fs);

#endif /* STORAGE_ASYNC_H */


